
			Developers FAQ

					      created: 03/01/2000 {14:18:04 PM}
					  last update: 12/05/2001 {19:46:21 PM}

Author:	Vince Darley
E-mail:	<vince@santafe.edu>
  mail:	317 Paseo de Peralta, Santa Fe, NM 87501, USA
   www:	<http://www.santafe.edu/~vince/>


For those developing modes, menus, and other features for Alpha and
Alphatk, or simply hacking away at existing code, this file contains
the answers to some frequently asked questions.  Feel free to suggest
new questions and answers (on the alphatcl-developers mailing list).

If you are sending files to any of the core developers of Alpha,
please ensure they are encoded in some way (whether binhex'd, stuffed,
macbinarized, or whatever).  Many of Alpha's .tcl and help files
contain ascii characters > 128, which are usually garbled when a file 
is sent as a plain attachment.

Ordinary Alpha(tk) 'users' will probably not find much of use here...

(Q1) I've added/changed some .tcl files but when I run Alpha and try
to use the new features, I get an error 'invalid command name
<myproc>'.  I'm sure myproc exists!

(A1) Tcl uses index files to work out how to locate previously unknown
procedures.  If 'myproc' is new, it presumably isn't in those index
files, and Tcl can't find it (except by chance, by loading a different
proc in the same file).  So the solution is to rebuild your tcl indices
-- the command is in the 'Alpha developer' menu.  Alternatively, in the Tcl
shell (cmd-Y) you can 'cd' to the correct directory and type:
'auto_mkindex .'  to rebuild just the index in that directory.  Another
quick option is to use the Tcl menu item 'rebuild tcl index for win'.

(Q2) I've added/changed some .tcl files but when I run Alpha my entire
package isn't even recognised.  Why not?

(A2) Alpha caches package information to avoid having to scan hundreds
of files on startup.  You need to rebuild your package indices (the
bottom of the Config->Packages menu).  Recent versions of AlphaTcl
check whether the number of files/folders have changed and does a
rebuild for you, which should avoid this problem.  Also see (A3)

(Q3) I made some minor changes to my alpha::feature/mode/menu command,
and Alpha hasn't noticed the change.

(A3) Alpha caches package information to avoid having to scan hundreds
of files on startup.  You need to rebuild your package indices (the
bottom of the Config->Packages menu).  Also see (A2)

(Q4) Why should I use minPos/maxPos/pos::math/pos::compare/pos::diff?
What's wrong with just using 'expr'?

(A4) Alpha's current windowing model simply uses numbers to represent 
positions relative to the start of the window.  However Alphatk uses a
more complex positioning scheme.  In the future we may change the
windowing model of Alpha.  So, if you only care about having your code
run on Alpha now, then 'expr' is fine.  For your code to run on
Alphatk now, and to avoid incompatibility if Alpha changes in the
future, you should use the pos:: functions.

(Q5) Does Alpha always use '\r' for line-endings?  What about
Unix/PC files?

(A5) You're best off simply assuming that a line-ending may be either 
'\r' or '\n'.  (Or sometimes a combination of the two).  In
particular, Alpha uses '\r', Alphatk uses '\n', and files on disk
may use any of \r, \n, or \r\n

(Q6) What's the difference between 'rebuild package indices' and
'rebuild Tcl indices'?

(A6) The former rebuild's Alpha's database of package details -- all
the information in those alpha::feature/mode/menu/extension commands.
The latter rebuilds Tcl's database of which procedures are in which
files.  Alpha's database is stored in your ${PREFS}:Cache:index 
directory.  Tcl's database is stored in the tclIndex (or tclIndexx) 
files in each directory in the 'Alpha:Tcl' hierarchy.

(Q7) What's the difference between: 'alpha::package require Alpha 7.2'
and 'alpha::package require AlphaTcl 7.2'?

(A7) AlphaTcl is the library of Tcl code which comes with Alpha and
Alphatk...  Most existing packages should only really test the version
of AlphaTcl.  When Alpha 8.0 is released, new commands may appear, or
old commands may have their behaviour slightly changed, in that case
you may wish to test the version of Alpha.  Note that Alpha 8 and
Alphatk 8 both use AlphaTcl versions 7.x at present.  So, you should
use 'alpha::package require AlphaTcl ...'.  Alpha 8, Alpha X and Alphatk
will all declare themselves as 'Alpha 8.x'.  The differences between
these three (and Alpha 7) are best ascertained by examining any of:
alpha::platform, info tclversion, tcl_platform(platform), tcl_platform(os).


